/*=============================================================================*
 *  Copyright 2004 The Apache Software Foundation
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *=============================================================================*/
package topics.expression;

import topics.Topic;
import topics.TopicSpaceSet;
import topics.expression.InvalidTopicExpressionException;
import topics.expression.TopicExpression;
import topics.expression.TopicExpressionException;
import topics.expression.TopicExpressionResolutionException;
import topics.expression.TopicPathDialectUnknownException;

/**
 * A <code>TopicExpressionEvaluator</code> is used to implement a topic expression evaluation against a
 * <code>TopicSpaceSet</code>. An evaluator can be registered with a <code>TopicExpressionEngine</code>,
 * which in turn calls the evaluator when a matching expression is found.
 */
public interface TopicExpressionEvaluator
{
   /**
    * Gets the URIs for the dialects that this evaluator can handle
    *
    * @return array of URIs supported by this evaluator
    */
   String[] getDialects(  );

   /**
    * Evaluates the expression over a TopicSpace and returns the set of matching topics.
    *
    * @param topicSpaceSet topic list associated with the service/resource
    * @param expression object passed by client representing the topic expression
    * @return the set of topics that matched the specified expression
    *
    * @throws TopicPathDialectUnknownException
    *                                  if the topic expression dialect is not supported
    * @throws TopicExpressionResolutionException
    *                                  if the expression could not be evaluated
    * @throws org.apache.ws.notification.topics.expression.InvalidTopicExpressionException
    *                                  if the topic expression is invalid
    * @throws TopicExpressionException if any other error occurs
    */
   Topic[] evaluate( TopicSpaceSet   topicSpaceSet,
                     TopicExpression expression )
   throws TopicPathDialectUnknownException, 
          TopicExpressionResolutionException, 
          InvalidTopicExpressionException, 
          TopicExpressionException;
}